doc: Add repo docs

diff --git a/doc/Makefile.am b/doc/Makefile.am
index b5acad6fbdedb6776922b0ab4be5f2e31853e084..ef1e549c994fd0cf4abbe6e4a06ef2214ae3b9d6 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -75,6 +75,7 @@ HTML_IMAGES=
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
 content_files= \
        overview.xml \
+       repo.xml \
        $(NULL)
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded

diff --git a/doc/ostree-docs.xml b/doc/ostree-docs.xml
index 33936555036aef827fe0be9c97567165e05d2083..af3fd0c787bbd166df980513f3c8013b8039dcc2 100644 (file)
--- a/doc/ostree-docs.xml
+++ b/doc/ostree-docs.xml
@@ -12,6 +12,7 @@
        </bookinfo>
 
        <xi:include href="overview.xml"/>
+       <xi:include href="repo.xml"/>
 
        <chapter xml:id="reference">
                <title>API Reference</title>

diff --git a/doc/repo.xml b/doc/repo.xml
new file mode 100644 (file)
index 0000000..ee367b9
--- /dev/null
+++ b/doc/repo.xml
@@ -0,0 +1,86 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<part id="repository">
+  <title>Anatomy of an OSTree repository</title>
+  <chapter id="repository-intro">
+    <title>Core object types and data model</title>
+    <para>
+      OSTree is deeply inspired by git.  It is worth taking some time
+      to familiarize yourself with <ulink
+      url="http://git-scm.com/book/en/Git-Internals">Git
+      Internals</ulink>, as this section will assume some knowledge of how
+      git works.
+    </para>
+    
+    <para>
+      Like git, OSTree is a userspace versioning filesystem.  Its
+      object types are similar to git; it has commit objects and
+      content objects.  Git has "tree" objects, whereas OSTree splits
+      them into "dirtree" and "dirmeta" objects.  But unlike git,
+      OSTree's checksums are SHA256.  Its content objects include uid,
+      gid, and extended attributes (but still no timestamps).
+    </para>
+    
+    <para>
+      Also like git, each commit in OSTree can have a parent.  It is
+      designed to store a history of your binary builds, just like git
+      stores a history of source control.  However, OSTree also makes
+      it easy to delete data, under the assumption that you can
+      regenerate it from source code.
+    </para>
+  </chapter>
+
+  <chapter id="repository-types">
+    <title>Repository types and locations</title>
+    
+    <para>
+      Also unlike git, an OSTree repository can be in one of two
+      separate modes: <literal>bare</literal> and
+      <literal>archive-z2</literal>.  A bare repository is one where
+      content files are just stored as regular files; it's designed to
+      be the source of a "hardlink farm", where each operating system
+      checkout is merely links into it.  If you want to store files
+      owned by e.g. root in this mode, you must run OSTree as root.
+      In contrast, the <literal>archive-z2</literal> mode is designed
+      for serving via plain HTTP.  Like tar files, it can be
+      read/written by non-root users.
+    </para>
+    
+    <para>
+      On an OSTree-deployed system, the "system repository" is
+      <filename class='directory'>/ostree/repo</filename>.  It can be
+      read by any uid, but only written by root.  Unless the
+      <literal>--repo</literal> argument is given to the
+      <command>ostree</command> command, it will operate on the system
+      repository.
+    </para>
+  </chapter>
+
+  <chapter id="refs">
+    <title>Refs</title>
+    <para>
+      Like git, OSTree uses "refs" to which are text files that point
+      to particular commits (i.e. filesystem trees).  For example, the
+      gnome-ostree operating system creates trees named like
+      <literal>gnome-ostree/buildmaster/x86_64-runtime</literal> and
+      <literal>gnome-ostree/buildmaster/x86_64-devel-debug</literal>.
+      These two refs point to two different generated filesystem
+      trees.  In this example, the "runtime" tree contains just enough
+      to run a basic GNOME system, and "devel-debug" contains all of
+      the developer tools.
+    </para>
+    
+    <para>
+      The <command>ostree</command> supports a simple syntax using the
+      carat <literal>^</literal> to refer to the parent of a given
+      commit.  For example,
+      <literal>gnome-ostree/buildmaster/x86_64-runtime^</literal>
+      refers to the previous build, and
+      <literal>gnome-ostree/buildmaster/x86_64-runtime^^</literal>
+      refers to the one before that.
+    </para>
+  </chapter>
+</part>